

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  
  <title>贡献 Ceph 文档 &mdash; Ceph Documentation</title>
  

  
  <link rel="stylesheet" href="../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/ceph.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/css/custom.css" type="text/css" />

  
  

  
  

  

  
  <!--[if lt IE 9]>
    <script src="../../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/jquery.js"></script>
        <script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
        <script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/doctools.js"></script>
        <script src="../../_static/sphinx_highlight.js"></script>
    
    <script type="text/javascript" src="../../_static/js/theme.js"></script>

    
    <link rel="index" title="Index" href="../../genindex/" />
    <link rel="search" title="Search" href="../../search/" />
    <link rel="next" title="安装 Ceph" href="../../install/" />
    <link rel="prev" title="加入 Ceph 社区！" href="../get-involved/" /> 
</head>

<body class="wy-body-for-nav">

   
  <header class="top-bar">
    <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../../" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="../">Ceph 简介</a></li>
      <li class="breadcrumb-item active">贡献 Ceph 文档</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../../_sources/start/documenting-ceph.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
  </header>
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: #eee" >
          

          
            <a href="../../" class="icon icon-home"> Ceph
          

          
          </a>

          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search/" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        
        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../">Ceph 简介</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../beginners-guide/">入门指南</a></li>
<li class="toctree-l2"><a class="reference internal" href="../hardware-recommendations/">硬件推荐</a></li>
<li class="toctree-l2"><a class="reference internal" href="../os-recommendations/">操作系统推荐</a></li>
<li class="toctree-l2"><a class="reference internal" href="../get-involved/">加入 Ceph 社区！</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">贡献 Ceph 文档</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#id1">文档在源码库里的位置</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id2">怎么看以前的 Ceph 文档</a></li>
<li class="toctree-l3"><a class="reference internal" href="#making-contributions">如何贡献</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id4">获取源代码</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id5">进入分支</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id6">开始更改</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id7">构建文档源码</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id9">提交变更</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id10">推送变更</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id11">发出接收请求</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id12">合并额外的提交</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id13">通知我们</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#id14">文档风格指南</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id15">标题</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id16">正文</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id17">段落分级标记</a></li>
<li class="toctree-l4"><a class="reference internal" href="#toc">TOC 和超链接</a></li>
<li class="toctree-l4"><a class="reference internal" href="#rst">RST 格式的怪异之处</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../install/">安装 Ceph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephadm/">Cephadm</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rados/">Ceph 存储集群</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../cephfs/">Ceph 文件系统</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rbd/">Ceph 块设备</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../radosgw/">Ceph 对象网关</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/">Ceph 管理器守护进程</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mgr/dashboard/">Ceph 仪表盘</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../monitoring/">监控概览</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../api/">API 文档</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../architecture/">体系结构</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/developer_guide/">开发者指南</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev/internals/">Ceph 内幕</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../governance/">项目管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../foundation/">Ceph 基金会</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../ceph-volume/">ceph-volume</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/general/">Ceph 版本（总目录）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../releases/">Ceph 版本（索引）</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../security/">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../hardware-monitoring/">硬件监控</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../glossary/">Ceph 术语</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../jaegertracing/">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../translation_cn/">中文版翻译资源</a></li>
</ul>

            
          
        </div>
        
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../">Ceph</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
<div id="dev-warning" class="admonition note">
  <p class="first admonition-title">Notice</p>
  <p class="last">This document is for a development version of Ceph.</p>
</div>
  <div id="docubetter" align="right" style="padding: 5px; font-weight: bold;">
    <a href="https://pad.ceph.com/p/Report_Documentation_Bugs">Report a Documentation Bug</a>
  </div>

  
  <section id="ceph">
<span id="documenting-ceph"></span><h1>贡献 Ceph 文档<a class="headerlink" href="#ceph" title="Permalink to this heading"></a></h1>
<p>想帮助 Ceph 项目可以贡献文档。
即使是小小的贡献也对 Ceph 项目有益。</p>
<p>纠正文档最简单的方法就是往 <cite>ceph-users&#64;ceph.io</cite> 发送电子邮件。
在标题行写上 “ATTN: DOCS” 或者 “Attention: Docs”
或者 “Attention: Documentation” 。
在 email 正文，写上要纠正的文本
（以便我在代码库里找到它）、还有你的更正。</p>
<p>纠正文档的另外一种方法是发出一个拉取请求。
向 Ceph 文档提出拉取请求的说明位于
<a class="reference internal" href="#making-contributions"><span class="std std-ref">如何贡献</span></a> 。</p>
<p>如果这是你第一次改进文档、或者假设你发现了一个小小的错误
（比如拼写错误或者错别字），发一封邮件比提出拉取请求更简单。
这次改进将归功于你，除非你向 Ceph 文档上游明确提出不要归功于你。</p>
<section id="id1">
<h2>文档在源码库里的位置<a class="headerlink" href="#id1" title="Permalink to this heading"></a></h2>
<p>Ceph 文档源码位于 Ceph 源码库的 <code class="docutils literal notranslate"><span class="pre">ceph/doc</span></code> 目录下，由 Python Sphinx 渲染成 HTML 和手册页。</p>
</section>
<section id="id2">
<h2>怎么看以前的 Ceph 文档<a class="headerlink" href="#id2" title="Permalink to this heading"></a></h2>
<p><a class="reference external" href="https://docs.ceph.com">https://docs.ceph.com</a> 链接默认展示最新版
（例如，假设 Reef 是最新版，那么
<a class="reference external" href="https://docs.ceph.com">https://docs.ceph.com</a> 默认展示的就是 Reef 的文档），
也可以查看较早版本的文档（例如 <code class="docutils literal notranslate"><span class="pre">quincy</span></code> ），
把 URL 里的版本名（如
<a class="reference external" href="https://docs.ceph.com/en/reef">https://docs.ceph.com/en/reef/</a> 里的 <code class="docutils literal notranslate"><span class="pre">reef</span></code> ）
替换成你想看的分支即可（如 <code class="docutils literal notranslate"><span class="pre">quincy</span></code> ， URL 就成了
<a class="reference external" href="https://docs.ceph.com/en/quincy/">https://docs.ceph.com/en/quincy/</a> ）。</p>
</section>
<section id="making-contributions">
<span id="id3"></span><h2>如何贡献<a class="headerlink" href="#making-contributions" title="Permalink to this heading"></a></h2>
<p>贡献文档和贡献源码的过程基本相同，唯一不同的就是你编译的是文档源码而不是程序源码。大致顺序（编译文档源码的顺序）如下：</p>
<ol class="arabic simple">
<li><p><a class="reference internal" href="#id4">获取源代码</a></p></li>
<li><p><a class="reference internal" href="#id5">进入分支</a></p></li>
<li><p><a class="reference internal" href="#id6">开始更改</a></p></li>
<li><p><a class="reference internal" href="#id7">构建文档源码</a></p></li>
<li><p><a class="reference internal" href="#id9">提交变更</a></p></li>
<li><p><a class="reference internal" href="#id10">推送变更</a></p></li>
<li><p><a class="reference internal" href="#id11">发出接收请求</a></p></li>
<li><p><a class="reference internal" href="#id13">通知我们</a></p></li>
</ol>
<section id="id4">
<h3>获取源代码<a class="headerlink" href="#id4" title="Permalink to this heading"></a></h3>
<p>Ceph 文档位于和源码同一仓库内的 <code class="docutils literal notranslate"><span class="pre">ceph/doc</span></code> 目录下，关于 github 和 Ceph 的关系细节情况见<a class="reference internal" href="../get-involved/#get-involved"><span class="std std-ref">加入 Ceph 社区！</span></a>。</p>
<p>最常用的贡献方法是<a class="reference external" href="https://help.github.com/articles/using-pull-requests">分支并拉取</a>。为此，必须先做到：</p>
<ol class="arabic">
<li><p>在本地安装 git 。在 Debian/Ubuntu 下用此命令：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><style type="text/css">
span.prompt1:before {
  content: "$ ";
}
</style><span class="prompt1">sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>git</span>
</pre></div></div><p>在 Fedora 下用此命令：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>git</span>
</pre></div></div><p>在 CentOS/RHEL 下用此命令：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>git</span>
</pre></div></div></li>
<li><p>在 <code class="docutils literal notranslate"><span class="pre">.gitconfig</span></code> 配置文件里写好自己的名字和邮件地址。</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[user]</span>
<span class="w">   </span><span class="na">email</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">{your-email-address}</span>
<span class="w">   </span><span class="na">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">{your-name}</span>
</pre></div>
</div>
<p>例如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>config<span class="w"> </span>--global<span class="w"> </span>user.name<span class="w"> </span><span class="s2">&quot;John Doe&quot;</span></span>
<span class="prompt1">git<span class="w"> </span>config<span class="w"> </span>--global<span class="w"> </span>user.email<span class="w"> </span>johndoe@example.com</span>
</pre></div></div></li>
<li><p>创建 <a class="reference external" href="http://github.com">github</a> 帐户（假如没有的话）。</p></li>
<li><p>创建 Ceph 项目的分支，见 <a class="reference external" href="https://github.com/ceph/ceph">https://github.com/ceph/ceph</a> 。</p></li>
<li><p>把你自己的 Ceph 分支项目克隆到本机。
这样就创建了“本地工作副本”。</p></li>
</ol>
<p>Ceph 文档按它自身的主要组件来分类组织。</p>
<ul class="simple">
<li><p><strong>Ceph 存储集群：</strong>Ceph 存储集群文档位于
<code class="docutils literal notranslate"><span class="pre">doc/rados</span></code> 目录下；</p></li>
<li><p><strong>Ceph 块设备：</strong>Ceph 块设备文档位于
<code class="docutils literal notranslate"><span class="pre">doc/rbd</span></code> 目录下；</p></li>
<li><p><strong>Ceph 对象存储：</strong>Ceph 对象存储文档位于
<code class="docutils literal notranslate"><span class="pre">doc/radosgw</span></code> 目录下；</p></li>
<li><p><strong>Ceph 文件系统：</strong>Ceph 文件系统文档位于
<code class="docutils literal notranslate"><span class="pre">doc/cephfs</span></code> 目录下；</p></li>
<li><p><strong>安装（快速）：</strong>快速入门文档位于
<code class="docutils literal notranslate"><span class="pre">doc/start</span></code> 目录下；</p></li>
<li><p><strong>安装（手动）：</strong>手动安装文档位于
<code class="docutils literal notranslate"><span class="pre">doc/install</span></code> 目录下；</p></li>
<li><p><strong>手册页：</strong>手册源码位于 <code class="docutils literal notranslate"><span class="pre">doc/man</span></code> 目录下；</p></li>
<li><p><strong>开发者：</strong>开发者文档位于 <code class="docutils literal notranslate"><span class="pre">doc/dev</span></code> 目录下；</p></li>
<li><p><strong>图片：</strong>如果你想上传文档，如 JPEG 或 PNG 文件，
应该放到 <code class="docutils literal notranslate"><span class="pre">doc/images</span></code> 目录下。</p></li>
</ul>
</section>
<section id="id5">
<h3>进入分支<a class="headerlink" href="#id5" title="Permalink to this heading"></a></h3>
<p>如果只是细小的变更，像修正排版错误、或换一种措辞，
直接提交到 <code class="docutils literal notranslate"><span class="pre">main</span></code> 分支（默认的）即可；
为当前版本的功能提供文档时也应该提交到 <code class="docutils literal notranslate"><span class="pre">main</span></code> 分支。
<code class="docutils literal notranslate"><span class="pre">main</span></code> 是最常用的分支。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>checkout<span class="w"> </span>main</span>
</pre></div></div><p>给未来版本提供文档时应该提交到 <code class="docutils literal notranslate"><span class="pre">next</span></code> 分支，
<code class="docutils literal notranslate"><span class="pre">next</span></code> 分支是第二常用的分支。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>checkout<span class="w"> </span>next</span>
</pre></div></div><p>你在为尚未发布的功能写文档时，
如果这部分文档和已追踪的某个问题有关，
或者想在它被合并到 <code class="docutils literal notranslate"><span class="pre">main</span></code> 分支前看看它在 ceph.com 网站上的预览，
你应该另外创建个分支。为标识这是个只包含文档的更新，
按惯例用 <code class="docutils literal notranslate"><span class="pre">wip-doc</span></code> 作前缀，
按这个格式 <code class="docutils literal notranslate"><span class="pre">wip-doc-{your-branch-name}</span></code> 。
如果此分支和 <a class="reference external" href="http://tracker.ceph.com/issues">http://tracker.ceph.com/issues</a> 里的某个问题相关，
分支名最好包含问题编号，
例如，如果某文档分支是为 #4000 这个问题写的，
按惯例这个分支名就是 <code class="docutils literal notranslate"><span class="pre">wip-doc-4000</span></code> ，
对应的问题追踪 URL 就是 <a class="reference external" href="http://tracker.ceph.com/issues/4000">http://tracker.ceph.com/issues/4000</a> 。</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>请不要把贡献的文档和源码混合到同一个提交里，
您的文档提交和源码提交分开时，
会简化审查进程。
我们强烈建议所有新增功能或配置选项的拉取请求也要包含一个文档提交，
描述一下相关的变更、选项。</p>
</div>
<p>创建分支前，确保本地和远程都没有同名的。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>branch<span class="w"> </span>-a<span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span>wip-doc-<span class="o">{</span>your-branch-name<span class="o">}</span></span>
</pre></div></div><p>如果确实不存在，就可以创建了：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>wip-doc-<span class="o">{</span>your-branch-name<span class="o">}</span></span>
</pre></div></div></section>
<section id="id6">
<h3>开始更改<a class="headerlink" href="#id6" title="Permalink to this heading"></a></h3>
<p>修改文档很简单，打开 restructuredText 文件、修改、保存即可。
相关的语法请参考 <a class="reference internal" href="#id14">文档风格指南</a> 。</p>
<p>新增文档要在 <code class="docutils literal notranslate"><span class="pre">doc</span></code> 目录或其子目录下新建 restructuredText 文件，
并以 <code class="docutils literal notranslate"><span class="pre">*.rst</span></code> 作后缀。
还必须包含对它的引用：
如超链接或目录条目。某个顶极目录中的 <code class="docutils literal notranslate"><span class="pre">index.rst</span></code> 文件通常也包含一个 TOC ，
你可以在这里添加新文件名。
所有文档都必须有标题，详情见<a class="reference internal" href="#id15">标题</a>。</p>
<p>你新建的文档不会自动被 <code class="docutils literal notranslate"><span class="pre">git</span></code> 跟踪，
如果想把它加进仓库，必须用 <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span> <span class="pre">{path-to-filename}</span></code> 命令。
比如，在 Ceph 仓库的顶极目录下，
把 <code class="docutils literal notranslate"><span class="pre">example.rst</span></code> 文件加到 <code class="docutils literal notranslate"><span class="pre">rados</span></code> 子目录下，
可以这样：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>add<span class="w"> </span>doc/rados/example.rst</span>
</pre></div></div><p>要删除一文档，应该用 <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">rm</span> <span class="pre">{path-to-filename}</span></code> ，
比如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>rm<span class="w"> </span>doc/rados/example.rst</span>
</pre></div></div><p>还必须从其他文档删除与之相关的引用。</p>
</section>
<section id="id7">
<h3>构建文档源码<a class="headerlink" href="#id7" title="Permalink to this heading"></a></h3>
<p>要想构建文档，先进入 <code class="docutils literal notranslate"><span class="pre">ceph</span></code> 库目录：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1"><span class="nb">cd</span><span class="w"> </span>ceph</span>
</pre></div></div><div class="admonition note">
<p class="admonition-title">Note</p>
<p>包含 <code class="docutils literal notranslate"><span class="pre">build-doc</span></code> 和 <code class="docutils literal notranslate"><span class="pre">serve-doc</span></code> 的目录必须加进
<code class="docutils literal notranslate"><span class="pre">PATH</span></code> 环境变量里，这些命令才能好好运行。</p>
</div>
<p>在 Debian/Ubuntu 、 Fedora 或 CentOS/RHEL 上执行此命令构建文档：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">admin/build-doc</span>
</pre></div></div><p>要扫描外部链接是否都可达，执行：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">admin/build-doc<span class="w"> </span>linkcheck</span>
</pre></div></div><p>执行 <code class="docutils literal notranslate"><span class="pre">admin/build-doc</span></code> 之后，它会在 <code class="docutils literal notranslate"><span class="pre">ceph</span></code> 下创建一个
<code class="docutils literal notranslate"><span class="pre">build-doc</span></code> 目录。你也许还得在 <code class="docutils literal notranslate"><span class="pre">ceph/build-doc</span></code> 下创建个目录用于 Javadoc 的输出。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">mkdir<span class="w"> </span>-p<span class="w"> </span>output/html/api/libcephfs-java/javadoc</span>
</pre></div></div><p><code class="docutils literal notranslate"><span class="pre">build-doc</span></code> 构建脚本可能会产生警告和报错，
有关语法的错误<strong>必须</strong>修复才能提交，
警告<strong>应该</strong>尽量消除。</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>你必须核实<strong>所有超链接</strong>，
损坏的超链接会中止构建过程。</p>
</div>
<p>文档构建完成后你就可以启动一个 HTTP 服务器、
通过 <code class="docutils literal notranslate"><span class="pre">http://localhost:8080/</span></code> 查看了：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">admin/serve-doc</span>
</pre></div></div><p>或者，你可以直接到 <code class="docutils literal notranslate"><span class="pre">build-doc/output</span></code> 下看看构建好的文档。那里应该有 <code class="docutils literal notranslate"><span class="pre">html</span></code> 目录和 <code class="docutils literal notranslate"><span class="pre">man</span></code> 目录分别存放着 HTML 和手册页格式的文档。</p>
<section id="id8">
<h4>构建源码（首次）<a class="headerlink" href="#id8" title="Permalink to this heading"></a></h4>
<p>Ceph 用 Python Sphinx 构建文档，此软件一般都没安装。
首次构建文档时，它会生成一个用于
doxygen 的 XML 树，这个过程比较耗时.</p>
<p>Python Sphinx 的依赖软件包根据发行版不同而有所区别。
首次构建文档时，如果你没安装必要工具，构建脚本会提示你。
要运行 Sphinx 并成功构建文档，至少要安装下面这些软件包：</p>
<style type="text/css">div.body h3{margin:5px 0px 0px 0px;}</style>
<table cellpadding="10"><colgroup><col width="30%"><col width="30%"><col width="30%"></colgroup><tbody valign="top"><tr><td><h3>Debian/Ubuntu</h3><ul class="simple">
<li><p>gcc</p></li>
<li><p>python3-dev</p></li>
<li><p>python3-pip</p></li>
<li><p>python3-sphinx</p></li>
<li><p>python3-venv</p></li>
<li><p>libxml2-dev</p></li>
<li><p>libxslt1-dev</p></li>
<li><p>doxygen</p></li>
<li><p>graphviz</p></li>
<li><p>ant</p></li>
<li><p>ditaa</p></li>
</ul>
</td><td><h3>Fedora</h3><ul class="simple">
<li><p>gcc</p></li>
<li><p>python-devel</p></li>
<li><p>python-pip</p></li>
<li><p>python-docutils</p></li>
<li><p>python-jinja2</p></li>
<li><p>python-pygments</p></li>
<li><p>python-sphinx</p></li>
<li><p>libxml2-devel</p></li>
<li><p>libxslt1-devel</p></li>
<li><p>doxygen</p></li>
<li><p>graphviz</p></li>
<li><p>ant</p></li>
<li><p>ditaa</p></li>
</ul>
</td><td><h3>CentOS/RHEL</h3><ul class="simple">
<li><p>gcc</p></li>
<li><p>python-devel</p></li>
<li><p>python-pip</p></li>
<li><p>python-docutils</p></li>
<li><p>python-jinja2</p></li>
<li><p>python-pygments</p></li>
<li><p>python-sphinx</p></li>
<li><p>libxml2-dev</p></li>
<li><p>libxslt1-dev</p></li>
<li><p>doxygen</p></li>
<li><p>graphviz</p></li>
<li><p>ant</p></li>
</ul>
</td></tr></tbody></table><p>缺少的依赖都要安装，基于 Debian/Ubuntu 发行版的系统可以用此命令安装：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>gcc<span class="w"> </span>python-dev<span class="w"> </span>python3-pip<span class="w"> </span>libxml2-dev<span class="w"> </span>libxslt-dev<span class="w"> </span>doxygen<span class="w"> </span>graphviz<span class="w"> </span>ant<span class="w"> </span>ditaa</span>
<span class="prompt1">sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>python3-sphinx<span class="w"> </span>python3-venv<span class="w"> </span>cython3</span>
</pre></div></div><p>在 Fedora 发行版上可以执行：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>gcc<span class="w"> </span>python-devel<span class="w"> </span>python-pip<span class="w"> </span>libxml2-devel<span class="w"> </span>libxslt-devel<span class="w"> </span>doxygen<span class="w"> </span>graphviz<span class="w"> </span>ant</span>
<span class="prompt1">sudo<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>html2text</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>python-jinja2<span class="w"> </span>python-pygments<span class="w"> </span>python-docutils<span class="w"> </span>python-sphinx</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>jericho-html<span class="w"> </span>ditaa</span>
</pre></div></div><p>在 CentOS/RHEL 发行版上，最好安装 <code class="docutils literal notranslate"><span class="pre">epel</span></code>
(Extra Packages for Enterprise Linux) 软件库，
因为它提供了很多默认软件库所没有的软件包。
可执行此命令安装 <code class="docutils literal notranslate"><span class="pre">epel</span></code> ：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm</span>
</pre></div></div><p>在 CentOS/RHEL 发行版上可以执行：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>gcc<span class="w"> </span>python-devel<span class="w"> </span>python-pip<span class="w"> </span>libxml2-devel<span class="w"> </span>libxslt-devel<span class="w"> </span>doxygen<span class="w"> </span>graphviz<span class="w"> </span>ant</span>
<span class="prompt1">sudo<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>html2text</span>
</pre></div></div><p>对于 CentOS/RHEL 发行版，其余软件包不包含在默认及 <code class="docutils literal notranslate"><span class="pre">epel</span></code> 软件库内，
所以得到 <a class="reference external" href="http://rpmfind.net/">http://rpmfind.net/</a> 找，然后到合适的镜像下载并安装它们，
比如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">wget<span class="w"> </span>http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-jinja2-2.7.2-2.el7.noarch.rpm</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>python-jinja2-2.7.2-2.el7.noarch.rpm</span>
<span class="prompt1">wget<span class="w"> </span>http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-pygments-1.4-9.el7.noarch.rpm</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>python-pygments-1.4-9.el7.noarch.rpm</span>
<span class="prompt1">wget<span class="w"> </span>http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>python-docutils-0.11-0.2.20130715svn7687.el7.noarch.rpm</span>
<span class="prompt1">wget<span class="w"> </span>http://rpmfind.net/linux/centos/7/os/x86_64/Packages/python-sphinx-1.1.3-11.el7.noarch.rpm</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>python-sphinx-1.1.3-11.el7.noarch.rpm</span>
</pre></div></div><p>Ceph 文档大量使用了 <a class="reference external" href="http://ditaa.sourceforge.net/">ditaa</a> ，
它没有对应的 CentOS/RHEL7 二进制包。
如果你要修改 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 图，
那你必须安装 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 才能确认你新增或修改的 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 图可以正确渲染。
你可以自己去找与 CentOS/RHEL7 发行版兼容的包，并手动安装。
在 CentOS/RHEL7 下 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 依赖下列软件包：</p>
<ul class="simple">
<li><p>jericho-html</p></li>
<li><p>jai-imageio-core</p></li>
<li><p>batik</p></li>
</ul>
<p>到 <a class="reference external" href="http://rpmfind.net/">http://rpmfind.net/</a> 找兼容的 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 及其依赖，
然后从某个镜像下载并安装它们。例如：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">wget<span class="w"> </span>http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/j/jericho-html-3.3-4.fc22.noarch.rpm</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>jericho-html-3.3-4.fc22.noarch.rpm</span>
<span class="prompt1">wget<span class="w"> </span>http://rpmfind.net/linux/centos/7/os/x86_64/Packages/jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>jai-imageio-core-1.2-0.14.20100217cvs.el7.noarch.rpm</span>
<span class="prompt1">wget<span class="w"> </span>http://rpmfind.net/linux/centos/7/os/x86_64/Packages/batik-1.8-0.12.svn1230816.el7.noarch.rpm</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>batik-1.8-0.12.svn1230816.el7.noarch.rpm</span>
<span class="prompt1">wget<span class="w"> </span>http://rpmfind.net/linux/fedora/linux/releases/22/Everything/x86_64/os/Packages/d/ditaa-0.9-13.r74.fc21.noarch.rpm</span>
<span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>ditaa-0.9-13.r74.fc21.noarch.rpm</span>
</pre></div></div><p>安装好所有这些包之后，就可以按照<a class="reference internal" href="#id7">构建文档源码</a>里的步骤构建文档了。</p>
</section>
</section>
<section id="id9">
<h3>提交变更<a class="headerlink" href="#id9" title="Permalink to this heading"></a></h3>
<p>Ceph文档的提交虽然简单，却遵循着严格的惯例：</p>
<ul class="simple">
<li><p>一次提交<strong>应该</strong>只涉及一个文件（方便回退），
也<strong>可以</strong>一次提交有关联的多个文件。
不相干的变更<strong>不应该</strong>放到同一提交内；</p></li>
<li><p>每个提交都<strong>必须</strong>有注释；</p></li>
<li><p>提交的注释<strong>必须</strong>以 <code class="docutils literal notranslate"><span class="pre">doc:</span></code> 打头（应严格遵守）；</p></li>
<li><p>注释摘要<strong>必须</strong>只有一行（应严格遵守）；</p></li>
<li><p>额外的注释<strong>可以</strong>写到摘要下面空一行的地方，
但应该简单明了；</p></li>
<li><p>提交<strong>可以</strong>包含 <code class="docutils literal notranslate"><span class="pre">Fixes:</span> <span class="pre">https://tracker.ceph.com/issues/{bug</span> <span class="pre">number}</span></code> 字样；</p></li>
<li><p>提交<strong>必须</strong>包含 <code class="docutils literal notranslate"><span class="pre">Signed-off-by:</span> <span class="pre">Firstname</span> <span class="pre">Lasname</span> <span class="pre">&lt;email&gt;</span></code> （应严格遵守）。</p></li>
</ul>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>请遵守前述惯例，特别是标明了 <code class="docutils literal notranslate"><span class="pre">（应严格遵守）</span></code> 的那些，否则你的提交会被打回，
修正后才能重新提交。</p>
</div>
<p>下面是个通用提交的注释（首选）：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="p">:</span> <span class="n">Fixes</span> <span class="n">a</span> <span class="n">spelling</span> <span class="n">error</span> <span class="ow">and</span> <span class="n">a</span> <span class="n">broken</span> <span class="n">hyperlink</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">John</span> <span class="n">Doe</span> <span class="o">&lt;</span><span class="n">john</span><span class="o">.</span><span class="n">doe</span><span class="nd">@gmail</span><span class="o">.</span><span class="n">com</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>下面的注释里有到 BUG 的引用。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="p">:</span> <span class="n">Fixes</span> <span class="n">a</span> <span class="n">spelling</span> <span class="n">error</span> <span class="ow">and</span> <span class="n">a</span> <span class="n">broken</span> <span class="n">hyperlink</span><span class="o">.</span>

<span class="n">Fixes</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">tracker</span><span class="o">.</span><span class="n">ceph</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">issues</span><span class="o">/</span><span class="mi">1234</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">John</span> <span class="n">Doe</span> <span class="o">&lt;</span><span class="n">john</span><span class="o">.</span><span class="n">doe</span><span class="nd">@gmail</span><span class="o">.</span><span class="n">com</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>下面的注释包含一句概要和详述，
在摘要和详述之间用空行隔开了：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="p">:</span> <span class="n">Added</span> <span class="n">mon</span> <span class="n">setting</span> <span class="n">to</span> <span class="n">monitor</span> <span class="n">config</span> <span class="n">reference</span>

<span class="n">Describes</span> <span class="s1">&#39;mon setting&#39;</span><span class="p">,</span> <span class="n">which</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">new</span> <span class="n">setting</span> <span class="n">added</span>
<span class="n">to</span> <span class="n">config_opts</span><span class="o">.</span><span class="n">h</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">John</span> <span class="n">Doe</span> <span class="o">&lt;</span><span class="n">john</span><span class="o">.</span><span class="n">doe</span><span class="nd">@gmail</span><span class="o">.</span><span class="n">com</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>执行下列命令提交变更：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>commit<span class="w"> </span>-a</span>
</pre></div></div><p>管理文档提交的一个比较简单的方法是用 <code class="docutils literal notranslate"><span class="pre">git</span></code> 的图形化前端，
如 <code class="docutils literal notranslate"><span class="pre">gitk</span></code> 提供了可查看仓库历史的图形界面；
<code class="docutils literal notranslate"><span class="pre">git-gui</span></code> 提供的图形界面可查看未提交的变更、
把未提交变更暂存起来、提交变更、
并推送到自己的 Ceph 分支仓库。</p>
<p>在 Debian/Ubuntu 上执行以下命令安装：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>gitk<span class="w"> </span>git-gui</span>
</pre></div></div><p>在 Fedora/CentOS/RHEL 上执行以下命令安装：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">sudo<span class="w"> </span>yum<span class="w"> </span>install<span class="w"> </span>gitk<span class="w"> </span>git-gui</span>
</pre></div></div><p>然后执行：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1"><span class="nb">cd</span><span class="w"> </span><span class="o">{</span>git-ceph-repo-path<span class="o">}</span></span>
<span class="prompt1">gitk</span>
</pre></div></div><p>最后，点击 <strong>File-&gt;Start git gui</strong> 打开图形界面。</p>
</section>
<section id="id10">
<h3>推送变更<a class="headerlink" href="#id10" title="Permalink to this heading"></a></h3>
<p>你完成一或多个提交后，必须从本地推送到位于 <code class="docutils literal notranslate"><span class="pre">github</span></code> 的仓库。
某些图形化工具（如 <code class="docutils literal notranslate"><span class="pre">git-gui</span></code> ）有推送菜单。如果你之前创建了分支：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>push<span class="w"> </span>origin<span class="w"> </span>wip-doc-<span class="o">{</span>your-branch-name<span class="o">}</span></span>
</pre></div></div><p>否则：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>push</span>
</pre></div></div></section>
<section id="id11">
<h3>发出接收请求<a class="headerlink" href="#id11" title="Permalink to this heading"></a></h3>
<p>前面已经说过了，你可以依照<a class="reference external" href="https://help.github.com/articles/using-pull-requests">分支并拉取</a>方法共享文档。</p>
</section>
<section id="id12">
<h3>合并额外的提交<a class="headerlink" href="#id12" title="Permalink to this heading"></a></h3>
<p>每个拉取请求（ pull request ）应该只关联一个提交（ commit ）。
如果您在新功能工作分支上做出了多个提交，则需要“合并（ squash ）”这些提交。
“合并”是一种特定类型“交互式重置（ interactive rebase ）”的俗称。
“合并”的方式有很多，但本例涉及的是有三个提交、
且三个提交中的改动都要保留的情形。这三个提交将被合并成一个提交。</p>
<ol class="arabic">
<li><p>先做出提交，稍后合并它们。</p>
<ol class="upperalpha">
<li><p>做出第一个提交。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">improve</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">entry</span>

<span class="n">Improve</span> <span class="n">the</span> <span class="n">glossary</span> <span class="n">entry</span> <span class="k">for</span> <span class="s2">&quot;CephX&quot;</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Zac</span> <span class="n">Dover</span> <span class="o">&lt;</span><span class="n">zac</span><span class="o">.</span><span class="n">dover</span><span class="nd">@proton</span><span class="o">.</span><span class="n">me</span><span class="o">&gt;</span>

<span class="c1"># Please enter the commit message for your changes. Lines starting</span>
<span class="c1"># with &#39;#&#39; will be ignored, and an empty message aborts the commit.</span>
<span class="c1">#</span>
<span class="c1"># On branch wip-doc-2023-03-28-glossary-cephx</span>
<span class="c1"># Changes to be committed:</span>
<span class="c1">#       modified:   glossary.rst</span>
<span class="c1">#</span>
</pre></div>
</div>
</li>
<li><p>做出第二个提交。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">add</span> <span class="n">link</span> <span class="n">to</span> <span class="n">architecture</span> <span class="n">doc</span>

<span class="n">Add</span> <span class="n">a</span> <span class="n">link</span> <span class="n">to</span> <span class="n">a</span> <span class="n">section</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">architecture</span> <span class="n">document</span><span class="p">,</span> <span class="n">which</span> <span class="n">link</span>
<span class="n">will</span> <span class="n">be</span> <span class="n">used</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">process</span> <span class="n">of</span> <span class="n">improving</span> <span class="n">the</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">glossary</span> <span class="n">entry</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Zac</span> <span class="n">Dover</span> <span class="o">&lt;</span><span class="n">zac</span><span class="o">.</span><span class="n">dover</span><span class="nd">@proton</span><span class="o">.</span><span class="n">me</span><span class="o">&gt;</span>

   <span class="c1"># Please enter the commit message for your changes. Lines starting</span>
   <span class="c1"># with &#39;#&#39; will be ignored, and an empty message aborts the commit.</span>
   <span class="c1">#</span>
   <span class="c1"># On branch wip-doc-2023-03-28-glossary-cephx</span>
   <span class="c1"># Your branch is up to date with &#39;origin/wip-doc-2023-03-28-glossary-cephx&#39;.</span>
   <span class="c1">#</span>
   <span class="c1"># Changes to be committed:</span>
   <span class="c1">#       modified:   architecture.rst</span>
</pre></div>
</div>
</li>
<li><p>做出第三个提交。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">link</span> <span class="n">to</span> <span class="n">Arch</span> <span class="n">doc</span> <span class="ow">in</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">glossary</span>

<span class="n">Link</span> <span class="n">to</span> <span class="n">the</span> <span class="n">Architecture</span> <span class="n">document</span> <span class="kn">from</span> <span class="nn">the</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">the</span>
<span class="n">Glossary</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Zac</span> <span class="n">Dover</span> <span class="o">&lt;</span><span class="n">zac</span><span class="o">.</span><span class="n">dover</span><span class="nd">@proton</span><span class="o">.</span><span class="n">me</span><span class="o">&gt;</span>

<span class="c1"># Please enter the commit message for your changes. Lines starting</span>
<span class="c1"># with &#39;#&#39; will be ignored, and an empty message aborts the commit.</span>
<span class="c1">#</span>
<span class="c1"># On branch wip-doc-2023-03-28-glossary-cephx</span>
<span class="c1"># Your branch is up to date with &#39;origin/wip-doc-2023-03-28-glossary-cephx&#39;.</span>
<span class="c1">#</span>
<span class="c1"># Changes to be committed:</span>
<span class="c1">#       modified:   glossary.rst</span>
</pre></div>
</div>
</li>
</ol>
</li>
<li><p>功能分支中现在有三个提交。
现在我们开始将它们合并为一个提交。</p>
<ol class="upperalpha">
<li><p>执行命令 <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">rebase</span> <span class="pre">-i</span> <span class="pre">main</span></code> ，它会把当前分支
（功能分支）重置到 <code class="docutils literal notranslate"><span class="pre">main</span></code> 分支：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>rebase<span class="w"> </span>-i<span class="w"> </span>main</span>
</pre></div></div></li>
<li><p>会出现一个提交列表，就是之前在功能分支上做出的那些提交，
样子类似下面：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pick</span> <span class="n">d395e500883</span> <span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">improve</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">entry</span>
<span class="n">pick</span> <span class="n">b34986e2922</span> <span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">add</span> <span class="n">link</span> <span class="n">to</span> <span class="n">architecture</span> <span class="n">doc</span>
<span class="n">pick</span> <span class="mi">74</span><span class="n">d0719735c</span> <span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">link</span> <span class="n">to</span> <span class="n">Arch</span> <span class="n">doc</span> <span class="ow">in</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">glossary</span>

<span class="c1"># Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands)</span>
<span class="c1">#</span>
<span class="c1"># Commands:</span>
<span class="c1"># p, pick &lt;commit&gt; = use commit</span>
<span class="c1"># r, reword &lt;commit&gt; = use commit, but edit the commit message</span>
<span class="c1"># e, edit &lt;commit&gt; = use commit, but stop for amending</span>
<span class="c1"># s, squash &lt;commit&gt; = use commit, but meld into previous commit</span>
<span class="c1"># f, fixup [-C | -c] &lt;commit&gt; = like &quot;squash&quot; but keep only the previous</span>
<span class="c1">#                    commit&#39;s log message, unless -C is used, in which case</span>
<span class="c1">#                    keep only this commit&#39;s message; -c is same as -C but</span>
<span class="c1">#                    opens the editor</span>
<span class="c1"># x, exec &lt;command&gt; = run command (the rest of the line) using shell</span>
<span class="c1"># b, break = stop here (continue rebase later with &#39;git rebase --continue&#39;)</span>
<span class="c1"># d, drop &lt;commit&gt; = remove commit</span>
<span class="c1"># l, label &lt;label&gt; = label current HEAD with a name</span>
<span class="c1"># t, reset &lt;label&gt; = reset HEAD to a label</span>
<span class="c1"># m, merge [-C &lt;commit&gt; | -c &lt;commit&gt;] &lt;label&gt; [# &lt;oneline&gt;]</span>
<span class="c1">#         create a merge commit using the original merge commit&#39;s</span>
<span class="c1">#         message (or the oneline, if no original merge commit was</span>
<span class="c1">#         specified); use -c &lt;commit&gt; to reword the commit message</span>
<span class="c1"># u, update-ref &lt;ref&gt; = track a placeholder for the &lt;ref&gt; to be updated</span>
<span class="c1">#                       to this position in the new commits. The &lt;ref&gt; is</span>
<span class="c1">#                       updated at the end of the rebase</span>
<span class="c1">#</span>
<span class="c1"># These lines can be re-ordered; they are executed from top to bottom.</span>
<span class="c1">#</span>
<span class="c1"># If you remove a line here THAT COMMIT WILL BE LOST.</span>
</pre></div>
</div>
<p>找到屏幕上显示 pick 的部分，这是需要您修改的部分。
现在有三个提交被标为 pick 。
我们选择其中一个继续标记为 pick ，
并将另外两个提交标记为 squash 。</p>
</li>
</ol>
</li>
<li><p>把三个提交中的两个标记为 <code class="docutils literal notranslate"><span class="pre">squash</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pick</span> <span class="n">d395e500883</span> <span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">improve</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">entry</span>
<span class="n">squash</span> <span class="n">b34986e2922</span> <span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">add</span> <span class="n">link</span> <span class="n">to</span> <span class="n">architecture</span> <span class="n">doc</span>
<span class="n">squash</span> <span class="mi">74</span><span class="n">d0719735c</span> <span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">link</span> <span class="n">to</span> <span class="n">Arch</span> <span class="n">doc</span> <span class="ow">in</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">glossary</span>

<span class="c1"># Rebase 0793495b9d1..74d0719735c onto 0793495b9d1 (3 commands)</span>
<span class="c1">#</span>
<span class="c1"># Commands:</span>
<span class="c1"># p, pick &lt;commit&gt; = use commit</span>
<span class="c1"># r, reword &lt;commit&gt; = use commit, but edit the commit message</span>
<span class="c1"># e, edit &lt;commit&gt; = use commit, but stop for amending</span>
<span class="c1"># s, squash &lt;commit&gt; = use commit, but meld into previous commit</span>
<span class="c1"># f, fixup [-C | -c] &lt;commit&gt; = like &quot;squash&quot; but keep only the previous</span>
<span class="c1">#                    commit&#39;s log message, unless -C is used, in which case</span>
<span class="c1">#                    keep only this commit&#39;s message; -c is same as -C but</span>
<span class="c1">#                    opens the editor</span>
<span class="c1"># x, exec &lt;command&gt; = run command (the rest of the line) using shell</span>
<span class="c1"># b, break = stop here (continue rebase later with &#39;git rebase --continue&#39;)</span>
<span class="c1"># d, drop &lt;commit&gt; = remove commit</span>
<span class="c1"># l, label &lt;label&gt; = label current HEAD with a name</span>
<span class="c1"># t, reset &lt;label&gt; = reset HEAD to a label</span>
<span class="c1"># m, merge [-C &lt;commit&gt; | -c &lt;commit&gt;] &lt;label&gt; [# &lt;oneline&gt;]</span>
<span class="c1">#         create a merge commit using the original merge commit&#39;s</span>
<span class="c1">#         message (or the oneline, if no original merge commit was</span>
<span class="c1">#         specified); use -c &lt;commit&gt; to reword the commit message</span>
<span class="c1"># u, update-ref &lt;ref&gt; = track a placeholder for the &lt;ref&gt; to be updated</span>
<span class="c1">#                       to this position in the new commits. The &lt;ref&gt; is</span>
<span class="c1">#                       updated at the end of the rebase</span>
<span class="c1">#</span>
<span class="c1"># These lines can be re-ordered; they are executed from top to bottom.</span>
<span class="c1">#</span>
<span class="c1"># If you remove a line here THAT COMMIT WILL BE LOST.</span>
</pre></div>
</div>
</li>
<li><p>现在，我们创建一条提交信息，
它适用于所有合并在一起的提交：</p>
<ol class="upperalpha">
<li><p>保存并关闭指定要合并的提交列表后，
会出现包含所有三条提交信息的列表，
如下所示：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is a combination of 3 commits.</span>
<span class="c1"># This is the 1st commit message:</span>

<span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">improve</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">entry</span>

<span class="n">Improve</span> <span class="n">the</span> <span class="n">glossary</span> <span class="n">entry</span> <span class="k">for</span> <span class="s2">&quot;CephX&quot;</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Zac</span> <span class="n">Dover</span> <span class="o">&lt;</span><span class="n">zac</span><span class="o">.</span><span class="n">dover</span><span class="nd">@proton</span><span class="o">.</span><span class="n">me</span><span class="o">&gt;</span>

<span class="c1"># This is the commit message #2:</span>

<span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">add</span> <span class="n">link</span> <span class="n">to</span> <span class="n">architecture</span> <span class="n">doc</span>

<span class="n">Add</span> <span class="n">a</span> <span class="n">link</span> <span class="n">to</span> <span class="n">a</span> <span class="n">section</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">architecture</span> <span class="n">document</span><span class="p">,</span> <span class="n">which</span> <span class="n">link</span>
<span class="n">will</span> <span class="n">be</span> <span class="n">used</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">process</span> <span class="n">of</span> <span class="n">improving</span> <span class="n">the</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">glossary</span> <span class="n">entry</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Zac</span> <span class="n">Dover</span> <span class="o">&lt;</span><span class="n">zac</span><span class="o">.</span><span class="n">dover</span><span class="nd">@proton</span><span class="o">.</span><span class="n">me</span><span class="o">&gt;</span>

<span class="c1"># This is the commit message #3:</span>

<span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">link</span> <span class="n">to</span> <span class="n">Arch</span> <span class="n">doc</span> <span class="ow">in</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">glossary</span>

<span class="n">Link</span> <span class="n">to</span> <span class="n">the</span> <span class="n">Architecture</span> <span class="n">document</span> <span class="kn">from</span> <span class="nn">the</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">the</span>
<span class="n">Glossary</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Zac</span> <span class="n">Dover</span> <span class="o">&lt;</span><span class="n">zac</span><span class="o">.</span><span class="n">dover</span><span class="nd">@proton</span><span class="o">.</span><span class="n">me</span><span class="o">&gt;</span>

<span class="c1"># Please enter the commit message for your changes. Lines starting</span>
<span class="c1"># with &#39;#&#39; will be ignored, and an empty message aborts the commit.</span>
<span class="c1">#</span>
<span class="c1"># Date:      Tue Mar 28 18:42:11 2023 +1000</span>
<span class="c1">#</span>
<span class="c1"># interactive rebase in progress; onto 0793495b9d1</span>
<span class="c1"># Last commands done (3 commands done):</span>
<span class="c1">#    squash b34986e2922 doc/glossary: add link to architecture doc</span>
<span class="c1">#    squash 74d0719735c doc/glossary: link to Arch doc in &quot;CephX&quot; glossary</span>
<span class="c1"># No commands remaining.</span>
<span class="c1"># You are currently rebasing branch &#39;wip-doc-2023-03-28-glossary-cephx&#39; on &#39;0793495b9d1&#39;.</span>
<span class="c1">#</span>
<span class="c1"># Changes to be committed:</span>
<span class="c1">#       modified:   doc/architecture.rst</span>
<span class="c1">#       modified:   doc/glossary.rst</span>
</pre></div>
</div>
</li>
<li><p>提交信息已改编成了此处所示更简单的格式：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span><span class="o">/</span><span class="n">glossary</span><span class="p">:</span> <span class="n">improve</span> <span class="s2">&quot;CephX&quot;</span> <span class="n">entry</span>

<span class="n">Improve</span> <span class="n">the</span> <span class="n">glossary</span> <span class="n">entry</span> <span class="k">for</span> <span class="s2">&quot;CephX&quot;</span><span class="o">.</span>

<span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Zac</span> <span class="n">Dover</span> <span class="o">&lt;</span><span class="n">zac</span><span class="o">.</span><span class="n">dover</span><span class="nd">@proton</span><span class="o">.</span><span class="n">me</span><span class="o">&gt;</span>

<span class="c1"># Please enter the commit message for your changes. Lines starting</span>
<span class="c1"># with &#39;#&#39; will be ignored, and an empty message aborts the commit.</span>
<span class="c1">#</span>
<span class="c1"># Date:      Tue Mar 28 18:42:11 2023 +1000</span>
<span class="c1">#</span>
<span class="c1"># interactive rebase in progress; onto 0793495b9d1</span>
<span class="c1"># Last commands done (3 commands done):</span>
<span class="c1">#    squash b34986e2922 doc/glossary: add link to architecture doc</span>
<span class="c1">#    squash 74d0719735c doc/glossary: link to Arch doc in &quot;CephX&quot; glossary</span>
<span class="c1"># No commands remaining.</span>
<span class="c1"># You are currently rebasing branch &#39;wip-doc-2023-03-28-glossary-cephx&#39; on &#39;0793495b9d1&#39;.</span>
<span class="c1">#</span>
<span class="c1"># Changes to be committed:</span>
<span class="c1">#       modified:   doc/architecture.rst</span>
<span class="c1">#       modified:   doc/glossary.rst</span>
</pre></div>
</div>
</li>
</ol>
</li>
<li><p>将本地工作副本中合并后的提交强制推送（ push ）到远程的上游分支。
之所以需要强制推送，是因为新合并的提交在远程分支中没有祖先（ ancestor ）。
如果你对此感到困惑，只需运行此命令，
先别多想：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">git<span class="w"> </span>push<span class="w"> </span>-f</span>
</pre></div></div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Enumerating</span> <span class="n">objects</span><span class="p">:</span> <span class="mi">9</span><span class="p">,</span> <span class="n">done</span><span class="o">.</span>
<span class="n">Counting</span> <span class="n">objects</span><span class="p">:</span> <span class="mi">100</span><span class="o">%</span> <span class="p">(</span><span class="mi">9</span><span class="o">/</span><span class="mi">9</span><span class="p">),</span> <span class="n">done</span><span class="o">.</span>
<span class="n">Delta</span> <span class="n">compression</span> <span class="n">using</span> <span class="n">up</span> <span class="n">to</span> <span class="mi">8</span> <span class="n">threads</span>
<span class="n">Compressing</span> <span class="n">objects</span><span class="p">:</span> <span class="mi">100</span><span class="o">%</span> <span class="p">(</span><span class="mi">5</span><span class="o">/</span><span class="mi">5</span><span class="p">),</span> <span class="n">done</span><span class="o">.</span>
<span class="n">Writing</span> <span class="n">objects</span><span class="p">:</span> <span class="mi">100</span><span class="o">%</span> <span class="p">(</span><span class="mi">5</span><span class="o">/</span><span class="mi">5</span><span class="p">),</span> <span class="mi">722</span> <span class="nb">bytes</span> <span class="o">|</span> <span class="mf">722.00</span> <span class="n">KiB</span><span class="o">/</span><span class="n">s</span><span class="p">,</span> <span class="n">done</span><span class="o">.</span>
<span class="n">Total</span> <span class="mi">5</span> <span class="p">(</span><span class="n">delta</span> <span class="mi">4</span><span class="p">),</span> <span class="n">reused</span> <span class="mi">0</span> <span class="p">(</span><span class="n">delta</span> <span class="mi">0</span><span class="p">),</span> <span class="n">pack</span><span class="o">-</span><span class="n">reused</span> <span class="mi">0</span>
<span class="n">remote</span><span class="p">:</span> <span class="n">Resolving</span> <span class="n">deltas</span><span class="p">:</span> <span class="mi">100</span><span class="o">%</span> <span class="p">(</span><span class="mi">4</span><span class="o">/</span><span class="mi">4</span><span class="p">),</span> <span class="n">completed</span> <span class="k">with</span> <span class="mi">4</span> <span class="n">local</span> <span class="n">objects</span><span class="o">.</span>
<span class="n">To</span> <span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="n">zdover23</span><span class="o">/</span><span class="n">ceph</span><span class="o">.</span><span class="n">git</span>
 <span class="o">+</span> <span class="n">b34986e2922</span><span class="o">..</span><span class="mf">.02e3</span><span class="n">a5cb763</span> <span class="n">wip</span><span class="o">-</span><span class="n">doc</span><span class="o">-</span><span class="mi">2023</span><span class="o">-</span><span class="mi">03</span><span class="o">-</span><span class="mi">28</span><span class="o">-</span><span class="n">glossary</span><span class="o">-</span><span class="n">cephx</span> <span class="o">-&gt;</span> <span class="n">wip</span><span class="o">-</span><span class="n">doc</span><span class="o">-</span><span class="mi">2023</span><span class="o">-</span><span class="mi">03</span><span class="o">-</span><span class="mi">28</span><span class="o">-</span><span class="n">glossary</span><span class="o">-</span><span class="n">cephx</span> <span class="p">(</span><span class="n">forced</span> <span class="n">update</span><span class="p">)</span>
</pre></div>
</div>
</li>
</ol>
</section>
<section id="id13">
<h3>通知我们<a class="headerlink" href="#id13" title="Permalink to this heading"></a></h3>
<p>如果发出的 PR 长时间没人审核，
请联系相应组件的负责人，询问一下这么久是什么原因。
组件负责人列表见 <a class="reference internal" href="../../governance/#ctl"><span class="std std-ref">组件小组负责人</span></a> 。</p>
</section>
</section>
<section id="id14">
<h2>文档风格指南<a class="headerlink" href="#id14" title="Permalink to this heading"></a></h2>
<p>Ceph 文档项目的目标之一就是可读性，
包括 restructuredText 和渲染后的 HTML 页面的可读性。
进入 Ceph 源码库，随便找个文档查看其源码，
你会发现它们在终端下就像已经渲染过的 HTML 页面一样清晰明了。
另外，也许你还看到 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 格式的图表渲染的很漂亮。</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span class="prompt1">less<span class="w"> </span>doc/architecture.rst</span>
</pre></div></div><p>为了维持一致性，请遵守下面的风格手册。</p>
<section id="id15">
<h3>标题<a class="headerlink" href="#id15" title="Permalink to this heading"></a></h3>
<ol class="arabic simple">
<li><p><strong>文档标题：</strong> 标题行的前、后各加一行 <code class="docutils literal notranslate"><span class="pre">=</span></code> ，
且标题行首、行尾各有一个空格，
详情见<a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickstart.html#document-title-subtitle">文档标题</a>。</p></li>
<li><p><strong>段落标题：</strong> 段标题行下是一行 <code class="docutils literal notranslate"><span class="pre">=</span></code> ，且标题行首、
行尾都没有空格；段标题前应该有两个空行（除非前面是内嵌引用）。
详情见<a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections">小节</a>。</p></li>
<li><p><strong>小节标题：</strong> 小节标题行下是一行 <code class="docutils literal notranslate"><span class="pre">_</span></code> ，
且行首、行尾都没有空格；段标题前应该有两个空行
（除非前面是内嵌引用）。</p></li>
</ol>
</section>
<section id="id16">
<h3>正文<a class="headerlink" href="#id16" title="Permalink to this heading"></a></h3>
<p>通常，我们把正文限制在 80 列之内，
这样它在任何标准终端内都可以正确显示，行首、行尾都不能有空格。
我们应该尽可能维持此惯例，包括文本、项目、文字文本
（允许例外）、表格、和 <code class="docutils literal notranslate"><span class="pre">ditaa</span></code> 图形。</p>
<ol class="arabic">
<li><p><strong>段落：</strong> 段落前后各有一空行，且宽度不超过 80 字符，
这样文档源码就可以在任何标准终端正确显示。</p></li>
<li><p><strong>引文文本：</strong> 要创建引文文本（如展示命令行用法），
前一段应以 <code class="docutils literal notranslate"><span class="pre">::</span></code> 结尾；
或者先加一个空行、然后在新行上输入 <code class="docutils literal notranslate"><span class="pre">::</span></code> 、
之后再加一个空行。
之后以 TAB （首选）或 3 个空格缩进，
开始输入引文了。</p></li>
<li><p><strong>缩进文本：</strong> 像要点这样的缩进文本（如： <code class="docutils literal notranslate"><span class="pre">-</span> <span class="pre">some</span> <span class="pre">text</span></code> ）
可能会延伸很多行，
后续行应该延续和首行缩进
（数字、圆点等）相同的起始列。</p>
<p>缩进文本也可以包含引文。这时，
缩进文本仍然用空格标记、引文仍用 TAB 标记。
按照这个惯例，你就可以额外增加缩进段落，
并在其中嵌入引文示例
（引文段前加空行，行前用空格缩进）。</p>
</li>
<li><p><strong>编号项目：</strong> 需编号的列表应该在行首用 <code class="docutils literal notranslate"><span class="pre">#</span></code> 标识以实现自动编号，
而不是手动标识，
这样在条目顺序变更时就不用重新编号了。</p></li>
<li><p><strong>代码示例：</strong> Ceph 文档中可以用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::&lt;language&gt;</span></code> 角色按语种对源码进行高亮显示，
对源代码应该这样标记。然而，
使用这个标签时将导致编号项目从 1 开始重新编号，
详情见<a class="reference external" href="http://sphinx-doc.org/markup/code.html">显示代码示例</a>。</p></li>
</ol>
</section>
<section id="id17">
<h3>段落分级标记<a class="headerlink" href="#id17" title="Permalink to this heading"></a></h3>
<p>Ceph 文档项目用<a class="reference internal" href="#id17">段落分级标记</a>来高亮显示要点。</p>
<ol class="arabic simple">
<li><p><strong>Tip:</strong> 提示：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">tip::</span></code> 指令标识额外信息，
以助读者或操作员脱困。</p></li>
<li><p><strong>Note:</strong> 注：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">note::</span></code> 指令来高亮显示一个要点。</p></li>
<li><p><strong>Important:</strong> 重要：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">important::</span></code> 指令来高亮显示重要依赖或警告
（如可能导致数据丢失的事情）。
尽量少用，因为它会渲染成红色背景。</p></li>
<li><p><strong>Version Added:</strong> 版本新增：用 <code class="docutils literal notranslate"><span class="pre">..versionadded::</span></code> 指令来标识新增功能或配置选项，这样用户才能知道此选项适用的最低版本。</p></li>
<li><p><strong>Version Changed:</strong> 版本变更：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">versionchanged::</span></code> 指令标识用法或配置选项的变更。</p></li>
<li><p><strong>Deprecated:</strong> 已过时：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">deprecated::</span></code> 指令标识不再推荐或将被移除的 CLI 用法、功能、或配置选项。</p></li>
<li><p><strong>Topic:</strong> 论题：用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">topic::</span></code> 指令来封装位于文档主体之外的文本。
详情见 <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic">topic 指令</a>。</p></li>
</ol>
</section>
<section id="toc">
<h3>TOC 和超链接<a class="headerlink" href="#toc" title="Permalink to this heading"></a></h3>
<p>所有文档都必须被链接到其他文档或列表内，
否则构建时会被警告。</p>
<p>Sphinx 管理的 Ceph 文档套件中的每个文档
（每个 <code class="docutils literal notranslate"><span class="pre">.rst</span></code> 文件）都必须链接到
(1) 文档套件中的另一个文档，或 (2) 目录 (TOC)。
如果文档套件中存在文档没有以这种方式链接，
则 <code class="docutils literal notranslate"><span class="pre">build-doc</span></code> 脚本在尝试构建文档时会产生警告。</p>
<p>Ceph 项目使用了 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">toctree::</span></code> 指令（详情见 <a class="reference external" href="http://sphinx-doc.org/markup/toctree.html">TOC 树</a>）。
渲染内容表（ TOC ）时，最好指定 <code class="docutils literal notranslate"><span class="pre">:maxdepth:</span></code> 参数，
这样渲染出的 TOC 不至于太长。</p>
<p>链接目标是个惟一标识符（如 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">_unique-target-id:</span></code> ）、
而且某一引用明确引用了它（如 <code class="docutils literal notranslate"><span class="pre">:ref:</span> <span class="pre">`uniq-target-id`</span></code> ），
这时应该优先用 <code class="docutils literal notranslate"><span class="pre">:ref:</span></code> 语法。
遵循此惯例的话，即使
<code class="docutils literal notranslate"><span class="pre">.rst</span></code> 源文件在 <code class="docutils literal notranslate"><span class="pre">ceph/doc</span></code> 内移动位置后链接仍然有效，
详情见<a class="reference external" href="http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref">交叉引用任意位置</a>。</p>
<section id="start-external-hyperlink-example">
<span id="id18"></span><h4>外部超链接实例<a class="headerlink" href="#start-external-hyperlink-example" title="Permalink to this heading"></a></h4>
<p>还可以创建一个指向文档某段落的链接，并在链接正文中显示自定义文本。
当保留的链接句子文本比明确引用链接部分的标题更重要时，
这种方法就很有用。</p>
<p>例如，链接到 Sphinx Python 文档生成器主页的 RST ，
生成一句 “Click here to learn more about Python Sphinx.” ，
像这样书写：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>``Click `here &lt;https://www.sphinx-doc.org&gt;`_ to learn more about Python
Sphinx.``
</pre></div>
</div>
<p>然后，渲染成这样：</p>
<p>Click <a class="reference external" href="https://www.sphinx-doc.org">here</a> to learn more about Python Sphinx. 。</p>
<p>请特别注意反引号后面的下划线。如果你忘了加下划线，
而这又是你第一天使用 RST ，那么你有可能得花一整天去找到底哪里出了问题，
却不知道自己只是漏掉了下划线。此外，
请特别注意替换文本（本例中为 “here” ）与小于号之间的空格，
小于号把链接目标与显示的文本分隔开来。
如果没有这个空格，链接将无法正常渲染。</p>
</section>
<section id="id19">
<h4>链接自定义<a class="headerlink" href="#id19" title="Permalink to this heading"></a></h4>
<p>根据 Ceph 在 Inktank 时代形成的惯例，
Ceph 项目的文档贡献者倾向于把
<code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">_Link</span> <span class="pre">Text:</span> <span class="pre">../path</span></code> 链接放在文档底部，
然后用 <code class="docutils literal notranslate"><span class="pre">:ref:`path`</span></code> 形式的引用链接到它们。
这一约定更受欢迎，因为这样文档在命令行界面中的可读性更好。
但截至 2023 年，我们不再偏爱其中一种。
使用哪种惯例能让文本更容易阅读，就采用哪种惯例。</p>
<p>使用句子的一部分作为超链接， <a class="reference external" href="docs.ceph.com">像这样</a>，不太好。
建议优先采用“参见 X ”这样的惯例。以下是一些推荐的表述方式：</p>
<ol class="arabic simple">
<li><p>详情见 <a class="reference external" href="docs.ceph.com">docs.ceph.com</a> 。</p></li>
<li><p>参见 <a class="reference external" href="docs.ceph.com">docs.ceph.com</a> 。</p></li>
</ol>
</section>
</section>
<section id="rst">
<h3>RST 格式的怪异之处<a class="headerlink" href="#rst" title="Permalink to this heading"></a></h3>
<section id="id22">
<h4>外部链接<a class="headerlink" href="#id22" title="Permalink to this heading"></a></h4>
<p id="external-link-with-inline-text">用下面的公式渲染链接，就是把读者导向 Ceph 文档之外的链接地址：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>`inline text &lt;http:www.foo.com&gt;`_
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>在内联文本和小于号之间不要丢了空格。</p>
<p>最后一个反引号后面别丢了下划线。</p>
<p>要链接到 Ceph 文档以外的地址，
必须在内联文本和外部地址前的角括号之间加上空格。
这个惯例与链接到 Ceph 文档内部位置的内联文本正好相反。
参阅 <a class="reference internal" href="#internal-link-with-inline-text"><span class="std std-ref">here</span></a>
以了解此惯例的实例。</p>
<p>如果您觉得这玩意儿不一致且令人困惑，您的感觉是对的。
它的确前后不一，令人困惑。</p>
</div>
<p>另请参阅 “<a class="reference internal" href="#start-external-hyperlink-example"><span class="std std-ref">外部超链接示例</span></a>” 。</p>
</section>
<section id="id23">
<h4>内部链接<a class="headerlink" href="#id23" title="Permalink to this heading"></a></h4>
<p>要链接到 Ceph 文档中的某个段落，您必须
（1）在该部分之前定义一个目标链接，然后（2）在文档中的另一个位置链接到该目标。
以下是目标和链接到这些目标的方式：</p>
<p>定义目标:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">_target</span><span class="p">:</span>

<span class="n">Title</span> <span class="n">of</span> <span class="n">Targeted</span> <span class="n">Section</span>
<span class="o">=========================</span>

<span class="n">Lorem</span> <span class="n">ipsum</span><span class="o">...</span>
</pre></div>
</div>
<p>链接到目标:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:ref:`target`
</pre></div>
</div>
<p id="internal-link-with-inline-text">链接到目标时带上内联文本：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:ref:`inline text&lt;target&gt;`
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>“inline text” 与紧随其后的角括号之间没有空格。这恰恰与
<a class="reference internal" href="#external-link-with-inline-text"><span class="std std-ref">链接到 Ceph 文档之外位置的内联文本</span></a>
语法相反。如果您觉得这似乎不一致且令人困惑，
您的感觉没错。它就是前后不一，令人困惑。</p>
</div>
</section>
<section id="id24">
<h4>在单词中标记粗体字符<a class="headerlink" href="#id24" title="Permalink to this heading"></a></h4>
<p>本节介绍如何将单词中的某些字母加粗，而让单词中的其他字母保持常规（非加粗）。</p>
<p>下面的单行段落就是一个例子：</p>
<p><strong>C</strong>eph <strong>F</strong>ile <strong>S</strong>ystem 。</p>
<p>在 RST 文本里，下面的写法行不通：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">**</span><span class="n">C</span><span class="o">**</span><span class="n">eph</span> <span class="o">**</span><span class="n">F</span><span class="o">**</span><span class="n">ile</span> <span class="o">**</span><span class="n">S</span><span class="o">**</span><span class="n">ystem</span>
</pre></div>
</div>
<p>必须使用转义字符 (\) 关闭加粗符号，如下所示：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">**</span><span class="n">C</span><span class="o">**</span>\<span class="n">eph</span> <span class="o">**</span><span class="n">F</span><span class="o">**</span>\<span class="n">ile</span> <span class="o">**</span><span class="n">S</span><span class="o">**</span>\<span class="n">ystem</span>
</pre></div>
</div>
</section>
</section>
</section>
</section>



<div id="support-the-ceph-foundation" class="admonition note">
  <p class="first admonition-title">Brought to you by the Ceph Foundation</p>
  <p class="last">The Ceph Documentation is a community resource funded and hosted by the non-profit <a href="https://ceph.io/en/foundation/">Ceph Foundation</a>. If you would like to support this and our other efforts, please consider <a href="https://ceph.io/en/foundation/join/">joining now</a>.</p>
</div>


           </div>
           
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="../get-involved/" class="btn btn-neutral float-left" title="加入 Ceph 社区！" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="../../install/" class="btn btn-neutral float-right" title="安装 Ceph" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2016, Ceph authors and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0).</p>
  </div>

   

</footer>
        </div>
      </div>

    </section>

  </div>
  

  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>